21 أغسطس 2025العربية

نظرة متعمقة في ديكورات JavaScript، واستكشاف صيغتها وحالات استخدامها لبرمجة البيانات الوصفية وأفضل الممارسات وتأثيرها على قابلية صيانة التعليمات البرمجية. يتضمن أمثلة عملية واعتبارات مستقبلية.

ديكورات JavaScript: تنفيذ برمجة البيانات الوصفية

تعتبر ديكورات JavaScript ميزة قوية تتيح لك إضافة بيانات وصفية وتعديل سلوك الفئات والأساليب والخصائص والمعلمات بطريقة إعلانية وقابلة لإعادة الاستخدام. وهي عبارة عن اقتراح في المرحلة الثالثة في عملية معايير ECMAScript وتستخدم على نطاق واسع مع TypeScript، التي لديها تنفيذها الخاص (المختلف قليلاً). ستوفر هذه المقالة نظرة عامة شاملة حول ديكورات JavaScript، مع التركيز على دورها في برمجة البيانات الوصفية وتوضيح استخدامها بأمثلة عملية.

ما هي ديكورات JavaScript؟

الديكورات هي نمط تصميم يعزز أو يعدل وظائف الكائن دون تغيير هيكله. في JavaScript، الديكورات هي أنواع خاصة من الإعلانات التي يمكن إرفاقها بالفئات أو الأساليب أو الوصول أو الخصائص أو المعلمات. إنها تستخدم الرمز @ متبوعًا بدالة سيتم تنفيذها عند تحديد العنصر المزخرف.

فكر في الديكورات على أنها دوال تأخذ العنصر المزخرف كمدخل وتعيد نسخة معدلة من هذا العنصر، أو تؤدي بعض التأثيرات الجانبية بناءً عليه. يوفر هذا طريقة نظيفة وأنيقة لإضافة وظائف دون تغيير الفئة أو الدالة الأصلية مباشرةً.

المفاهيم الأساسية:

دالة الديكور: الدالة التي يسبقها الرمز @. تتلقى معلومات حول العنصر المزخرف ويمكنها تعديله.
العنصر المزخرف: الفئة أو الأسلوب أو الوصول أو الخاصية أو المعلمة التي تم تزيينها.
البيانات الوصفية: البيانات التي تصف البيانات. غالبًا ما تستخدم الديكورات لربط البيانات الوصفية بعناصر التعليمات البرمجية.

الصيغة والهيكل

الصيغة الأساسية للديكور هي كما يلي:

@decorator
class MyClass {
  // أعضاء الفئة
}

هنا، @decorator هي دالة الديكور و MyClass هي الفئة المزخرفة. يتم استدعاء دالة الديكور عند تحديد الفئة ويمكنها الوصول إلى تعريف الفئة وتعديله.

يمكن للديكورات أيضًا قبول الوسائط، والتي يتم تمريرها إلى دالة الديكور نفسها:

@loggable(true, "رسالة مخصصة")
class MyClass {
  // أعضاء الفئة
}

في هذه الحالة، loggable هي دالة مصنع الديكور، والتي تأخذ الوسائط وتعيد دالة الديكور الفعلية. يتيح ذلك ديكورات أكثر مرونة وقابلة للتكوين.

أنواع الديكورات

هناك أنواع مختلفة من الديكورات، اعتمادًا على ما تزينه:

ديكورات الفئة: يتم تطبيقها على الفئات.
ديكورات الأسلوب: يتم تطبيقها على الأساليب داخل الفئة.
ديكورات الوصول: يتم تطبيقها على أدوات الوصول إلى getter و setter.
ديكورات الخصائص: يتم تطبيقها على خصائص الفئة.
ديكورات المعلمات: يتم تطبيقها على معلمات الأسلوب.

ديكورات الفئة

تستخدم ديكورات الفئة لتعديل أو تعزيز سلوك الفئة. يتلقون مُنشئ الفئة كوسيطة ويمكنهم إرجاع مُنشئ جديد لاستبدال المُنشئ الأصلي. يتيح لك ذلك إضافة وظائف مثل التسجيل أو حقن التبعية أو إدارة الحالة.

مثال:

function loggable(constructor: Function) {
  console.log("تم إنشاء الفئة " + constructor.name + ".");
}

@loggable
class User {
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const user = new User("Alice"); // الإخراجات: تم إنشاء الفئة User.

في هذا المثال، يقوم الديكور loggable بتسجيل رسالة في وحدة التحكم كلما تم إنشاء مثيل جديد للفئة User. يمكن أن يكون هذا مفيدًا لتصحيح الأخطاء أو المراقبة.

ديكورات الأسلوب

تستخدم ديكورات الأسلوب لتعديل سلوك الأسلوب داخل الفئة. يتلقون الوسائط التالية:

target: النموذج الأولي للفئة.
propertyKey: اسم الأسلوب.
descriptor: واصف الخاصية للأسلوب.

يتيح لك الواصف الوصول إلى سلوك الأسلوب وتعديله، مثل تغليفه بمنطق إضافي أو إعادة تعريفه بالكامل.

مثال:

function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`استدعاء الأسلوب ${propertyKey} بالوسائط: ${args}`);
    const result = originalMethod.apply(this, args);
    console.log(`أرجع الأسلوب ${propertyKey}: ${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(a: number, b: number): number {
    return a + b;
  }
}

const calculator = new Calculator();
const sum = calculator.add(5, 3); // الإخراجات تسجل لاستدعاء الأسلوب والقيمة المرجعة

في هذا المثال، يقوم الديكور logMethod بتسجيل وسائط الأسلوب والقيمة المرجعة. يمكن أن يكون هذا مفيدًا لتصحيح الأخطاء ومراقبة الأداء.

ديكورات الوصول

تشبه ديكورات الوصول ديكورات الأسلوب ولكن يتم تطبيقها على أدوات الوصول إلى getter و setter. يتلقون نفس وسائط ديكورات الأسلوب ويسمحون لك بتعديل سلوك أداة الوصول.

مثال:

function validate(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalSet = descriptor.set;

  descriptor.set = function (value: any) {
    if (value < 0) {
      throw new Error("يجب أن تكون القيمة غير سالبة.");
    }
    originalSet.call(this, value);
  };
}

class Temperature {
  private _celsius: number;

  constructor(celsius: number) {
    this._celsius = celsius;
  }

  @validate
  set celsius(value: number) {
    this._celsius = value;
  }

  get celsius(): number {
    return this._celsius;
  }
}

const temperature = new Temperature(25);
temperature.celsius = 30; // صالح
// temperature.celsius = -10; // يطرح خطأ

في هذا المثال، يضمن الديكور validate أن قيمة درجة الحرارة غير سالبة. يمكن أن يكون هذا مفيدًا لفرض تكامل البيانات.

ديكورات الخصائص

تستخدم ديكورات الخصائص لتعديل سلوك خاصية الفئة. يتلقون الوسائط التالية:

target: النموذج الأولي للفئة (للخصائص المثيلة) أو مُنشئ الفئة (للخصائص الثابتة).
propertyKey: اسم الخاصية.

يمكن استخدام ديكورات الخصائص لتحديد البيانات الوصفية أو تعديل واصف الخاصية.

مثال:

function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Configuration {
  @readonly
  apiUrl: string = "https://api.example.com";
}

const config = new Configuration();
// config.apiUrl = "https://newapi.example.com"; // يطرح خطأ في الوضع الصارم

في هذا المثال، يجعل الديكور readonly الخاصية apiUrl للقراءة فقط، مما يمنع تعديلها بعد التهيئة. يمكن أن يكون هذا مفيدًا لتحديد قيم التكوين غير القابلة للتغيير.

ديكورات المعلمات

تستخدم ديكورات المعلمات لتعديل سلوك معلمة الأسلوب. يتلقون الوسائط التالية:

target: النموذج الأولي للفئة (للأساليب المثيلة) أو مُنشئ الفئة (للأساليب الثابتة).
propertyKey: اسم الأسلوب.
parameterIndex: فهرس المعلمة في قائمة معلمات الأسلوب.

تستخدم ديكورات المعلمات بشكل أقل شيوعًا من الأنواع الأخرى من الديكورات، ولكنها يمكن أن تكون مفيدة للتحقق من صحة معلمات الإدخال أو حقن التبعيات.

مثال:

function required(target: any, propertyKey: string, parameterIndex: number) {
  const existingRequiredParameters: number[] = Reflect.getOwnMetadata(propertyKey, target, "required") || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata(propertyKey, existingRequiredParameters, target, "required");
}

function validateMethod(target: any, propertyName: string, descriptor: PropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(propertyName, target, "required");
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (arguments[parameterIndex] === null || arguments[parameterIndex] === undefined) {
          throw new Error(`الوسيطة المطلوبة مفقودة في الفهرس ${parameterIndex}`);
        }
      }
    }

    return method.apply(this, arguments);
  };
}


class ArticleService {
  create(
    @required title: string,
    @required content: string
  ): void {
    console.log(`إنشاء مقال بالعنوان: ${title} والمحتوى: ${content}`);
  }
}

const service = new ArticleService();
// service.create("مقالتي", null); // يطرح خطأ
service.create("مقالتي", "محتوى المقال"); // صالح

في هذا المثال، يضع الديكور required علامة على المعلمات على أنها مطلوبة، ويضمن الديكور validateMethod أن هذه المعلمات ليست فارغة أو غير محددة. يمكن أن يكون هذا مفيدًا لفرض التحقق من صحة إدخال الأسلوب.

برمجة البيانات الوصفية باستخدام الديكورات

تعتبر برمجة البيانات الوصفية أحد أقوى حالات استخدام الديكورات. البيانات الوصفية هي بيانات حول البيانات. في سياق البرمجة، إنها بيانات تصف بنية التعليمات البرمجية وسلوكها والغرض منها. توفر الديكورات طريقة نظيفة وإعلانية لربط البيانات الوصفية بالفئات والأساليب والخصائص والمعلمات.

واجهة برمجة تطبيقات Reflect Metadata

واجهة برمجة تطبيقات Reflect Metadata هي واجهة برمجة تطبيقات قياسية تتيح لك تخزين واسترداد البيانات الوصفية المرتبطة بالكائنات. يوفر الوظائف التالية:

Reflect.defineMetadata(key, value, target, propertyKey): يحدد البيانات الوصفية لخاصية معينة من الكائن.
Reflect.getMetadata(key, target, propertyKey): يسترد البيانات الوصفية لخاصية معينة من الكائن.
Reflect.hasMetadata(key, target, propertyKey): يتحقق مما إذا كانت البيانات الوصفية موجودة لخاصية معينة من الكائن.
Reflect.deleteMetadata(key, target, propertyKey): يحذف البيانات الوصفية لخاصية معينة من الكائن.

يمكنك استخدام هذه الوظائف جنبًا إلى جنب مع الديكورات لربط البيانات الوصفية بعناصر التعليمات البرمجية الخاصة بك.

مثال: تحديد واسترداد البيانات الوصفية

import 'reflect-metadata';

const logKey = "log";

function log(message: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    Reflect.defineMetadata(logKey, message, target, key);

    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(Reflect.getMetadata(logKey, target, key));
      const result = originalMethod.apply(this, args);
      return result;
    }

    return descriptor;
  }
}

class Example {
  @log("تنفيذ الأسلوب")
  myMethod(arg: string): string {
    return `تم استدعاء الأسلوب مع ${arg}`;
  }
}

const example = new Example();
example.myMethod("Hello"); // الإخراجات: تنفيذ الأسلوب، تم استدعاء الأسلوب مع Hello

في هذا المثال، يستخدم الديكور log واجهة برمجة تطبيقات Reflect Metadata لربط رسالة سجل بالأسلوب myMethod. عند استدعاء الأسلوب، يسترد الديكور الرسالة ويسجلها في وحدة التحكم.

حالات الاستخدام لبرمجة البيانات الوصفية

تتمتع برمجة البيانات الوصفية باستخدام الديكورات بالعديد من التطبيقات العملية، بما في ذلك:

التسلسل وإلغاء التسلسل: قم بتعليق الخصائص بالبيانات الوصفية للتحكم في كيفية تسلسلها أو إلغاء تسلسلها من/إلى JSON أو تنسيقات أخرى. يمكن أن يكون هذا مفيدًا عند التعامل مع البيانات من واجهات برمجة التطبيقات الخارجية أو قواعد البيانات، خاصة في الأنظمة الموزعة التي تتطلب تحويل البيانات عبر منصات مختلفة (على سبيل المثال، تحويل تنسيقات التاريخ بين المعايير الإقليمية المختلفة). تخيل منصة تجارة إلكترونية تتعامل مع عناوين الشحن الدولية، حيث يمكنك استخدام البيانات الوصفية لتحديد تنسيق العنوان الصحيح وقواعد التحقق من الصحة لكل بلد.
حقن التبعية: استخدم البيانات الوصفية لتحديد التبعيات التي يجب حقنها في فئة. يؤدي ذلك إلى تبسيط إدارة التبعيات وتعزيز الاقتران الضعيف. ضع في اعتبارك بنية الخدمات الصغيرة حيث تعتمد الخدمات على بعضها البعض. يمكن للديكورات والبيانات الوصفية تسهيل الحقن الديناميكي لعملاء الخدمة بناءً على التكوين، مما يتيح سهولة التوسع وتحمل الأخطاء.
التحقق من الصحة: حدد قواعد التحقق من الصحة كبيانات وصفية واستخدم الديكورات للتحقق من صحة البيانات تلقائيًا. يضمن هذا تكامل البيانات ويقلل من التعليمات البرمجية القياسية. على سبيل المثال، يحتاج تطبيق التمويل العالمي إلى الامتثال للوائح مالية إقليمية مختلفة. يمكن للبيانات الوصفية تحديد قواعد التحقق من الصحة لتنسيقات العملة وحسابات الضرائب وحدود المعاملات بناءً على موقع المستخدم، مما يضمن الامتثال للقوانين المحلية.
التوجيه والبرامج الوسيطة: استخدم البيانات الوصفية لتحديد المسارات والبرامج الوسيطة لتطبيقات الويب. يؤدي هذا إلى تبسيط تكوين تطبيقك ويجعله أكثر قابلية للصيانة. يمكن لشبكة توصيل المحتوى (CDN) الموزعة عالميًا استخدام البيانات الوصفية لتحديد سياسات التخزين المؤقت وقواعد التوجيه بناءً على نوع المحتوى وموقع المستخدم، مما يؤدي إلى تحسين الأداء وتقليل زمن الوصول للمستخدمين في جميع أنحاء العالم.
التفويض والمصادقة: اربط الأدوار والأذونات ومتطلبات المصادقة بالأساليب والفئات، مما يسهل سياسات الأمان الإعلانية. تخيل شركة متعددة الجنسيات لديها موظفين في أقسام ومواقع مختلفة. يمكن للديكورات تحديد قواعد التحكم في الوصول بناءً على دور المستخدم وقسمه وموقعه، مما يضمن أن الموظفين المصرح لهم فقط يمكنهم الوصول إلى البيانات والوظائف الحساسة.

أفضل الممارسات

عند استخدام ديكورات JavaScript، ضع في اعتبارك أفضل الممارسات التالية:

حافظ على بساطة الديكورات: يجب أن تكون الديكورات مركزة وتؤدي مهمة واحدة محددة جيدًا. تجنب المنطق المعقد داخل الديكورات للحفاظ على إمكانية القراءة والصيانة.
استخدم مصانع الديكور: استخدم مصانع الديكور للسماح بالديكورات القابلة للتكوين. هذا يجعل الديكورات الخاصة بك أكثر مرونة وقابلة لإعادة الاستخدام.
تجنب الآثار الجانبية: يجب أن تركز الديكورات بشكل أساسي على تعديل العنصر المزخرف أو ربط البيانات الوصفية به. تجنب إجراء آثار جانبية معقدة داخل الديكورات التي قد تجعل فهم التعليمات البرمجية وتصحيحها أكثر صعوبة.
استخدم TypeScript: يوفر TypeScript دعمًا ممتازًا للديكورات، بما في ذلك التحقق من النوع و IntelliSense. يمكن أن يساعدك استخدام TypeScript في اكتشاف الأخطاء مبكرًا وتحسين تجربة التطوير الخاصة بك.
وثق الديكورات الخاصة بك: وثق الديكورات الخاصة بك بوضوح لشرح الغرض منها وكيفية استخدامها. هذا يجعل من السهل على المطورين الآخرين فهم الديكورات الخاصة بك واستخدامها بشكل صحيح.
ضع في اعتبارك الأداء: على الرغم من أن الديكورات قوية، إلا أنها يمكن أن تؤثر أيضًا على الأداء. كن على دراية بآثار الأداء المترتبة على الديكورات الخاصة بك، خاصة في التطبيقات ذات الأهمية البالغة للأداء.

أمثلة على التدويل باستخدام الديكورات

يمكن أن تساعد الديكورات في التدويل (i18n) والترجمة (l10n) عن طريق ربط البيانات والسلوك الخاصين بالموقع بمكونات التعليمات البرمجية:

مثال: تنسيق التاريخ المترجم

import 'reflect-metadata';

interface DateFormatOptions {
  locale: string;
  options?: Intl.DateTimeFormatOptions;
}

const dateFormatKey = 'dateFormat';

function formatDate(options: DateFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(dateFormatKey, options, target, propertyKey);
  };
}

class Event {
  @formatDate({ locale: 'fr-FR', options: { year: 'numeric', month: 'long', day: 'numeric' } })
  startDate: Date;

  constructor(startDate: Date) {
    this.startDate = startDate;
  }

  getFormattedStartDate(): string {
    const options: DateFormatOptions = Reflect.getMetadata(dateFormatKey, Object.getPrototypeOf(this), 'startDate');
    return this.startDate.toLocaleDateString(options.locale, options.options);
  }
}

const event = new Event(new Date());
console.log(event.getFormattedStartDate()); // إخراجات التاريخ بالتنسيق الفرنسي

مثال: تنسيق العملة بناءً على موقع المستخدم

import 'reflect-metadata';

interface CurrencyFormatOptions {
  locale: string;
  currency: string;
}

const currencyFormatKey = 'currencyFormat';

function formatCurrency(options: CurrencyFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(currencyFormatKey, options, target, propertyKey);
  };
}

class Product {
  @formatCurrency({ locale: 'de-DE', currency: 'EUR' })
  price: number;

  constructor(price: number) {
    this.price = price;
  }

  getFormattedPrice(): string {
    const options: CurrencyFormatOptions = Reflect.getMetadata(currencyFormatKey, Object.getPrototypeOf(this), 'price');
    return this.price.toLocaleString(options.locale, { style: 'currency', currency: options.currency });
  }
}

const product = new Product(99.99);
console.log(product.getFormattedPrice()); // إخراجات السعر بتنسيق اليورو الألماني

اعتبارات مستقبلية

تعتبر ديكورات JavaScript ميزة متطورة، ولا يزال المعيار قيد التطوير. تتضمن بعض الاعتبارات المستقبلية:

التوحيد القياسي: لا يزال معيار ECMAScript للديكورات قيد التقدم. مع تطور المعيار، قد تكون هناك تغييرات في صيغة الديكورات وسلوكها.
تحسين الأداء: مع زيادة استخدام الديكورات على نطاق واسع، ستكون هناك حاجة إلى تحسينات في الأداء لضمان عدم تأثيرها سلبًا على أداء التطبيق.
دعم الأدوات: سيؤدي تحسين دعم الأدوات للديكورات، مثل تكامل IDE وأدوات تصحيح الأخطاء، إلى تسهيل استخدام المطورين للديكورات بشكل فعال.

الخلاصة

تعتبر ديكورات JavaScript أداة قوية لتنفيذ برمجة البيانات الوصفية وتحسين سلوك التعليمات البرمجية الخاصة بك. باستخدام الديكورات، يمكنك إضافة وظائف بطريقة نظيفة وإعلانية وقابلة لإعادة الاستخدام. يؤدي هذا إلى تعليمات برمجية أكثر قابلية للصيانة والاختبار والتطوير. يعد فهم الأنواع المختلفة من الديكورات وكيفية استخدامها بفعالية أمرًا ضروريًا لتطوير JavaScript الحديث. تفتح الديكورات، خاصةً عند دمجها مع واجهة برمجة تطبيقات Reflect Metadata، مجموعة من الاحتمالات، من حقن التبعية والتحقق من الصحة إلى التسلسل والتوجيه، مما يجعل التعليمات البرمجية الخاصة بك أكثر تعبيرًا وأسهل في الإدارة.